﻿using wwl.Domain.Entities.Common;

namespace wwl.Domain.Entities.Rbac
{
  /// <summary>
  /// 角色权限关联实体（DDD 关联实体）
  /// 作为角色聚合根和权限聚合根之间的关联桥梁，实现多对多的权限授予关系
  /// 核心价值：建立"角色-权限"的映射关系，构成RBAC权限模型的核心数据链路
  /// 设计理念：通过角色聚合权限，通过用户关联角色，实现灵活的权限分配和管理
  /// </summary>
  public class RolePermission : BaseEntity, ITenantAware
  {
    /// <summary>
    /// 角色唯一标识（关联角色聚合根）
    /// </summary>
    /// <remarks>
    /// 1. 权限承载主体：通过 RoleId 标识被授予权限的角色，建立权限的集体分配机制。
    /// 2. 外键完整性：在数据库层面通过外键约束确保关联的角色存在，维护数据引用的一致性。
    /// 3. 批量授权：通过角色实现权限的批量分配，避免为每个用户单独配置权限的管理成本。
    /// 4. 权限继承：用户通过关联角色自动继承该角色的所有权限，实现权限的层级传递。
    /// </remarks>
    public string RoleId { get; set; } = string.Empty;

    /// <summary>
    /// 权限唯一标识（关联权限聚合根）
    /// </summary>
    /// <remarks>
    /// 1. 权限具体内容：通过 PermissionId 标识被授予的具体权限项，定义角色的能力范围。
    /// 2. 细粒度控制：每个 PermissionId 对应一个具体的系统资源或操作权限，实现精确的访问控制。
    /// 3. 权限验证：在访问控制时通过 PermissionId 快速匹配所需权限，支撑高效的权限校验逻辑。
    /// 4. 级联保护：权限删除时自动清理所有相关的角色权限关联，防止存在无效的权限引用。
    /// </remarks>
    public string PermissionId { get; set; } = string.Empty;

    /// <summary>
    /// 租户标识（多租户权限分配隔离）
    /// </summary>
    /// <remarks>
    /// 1. 租户边界控制：确保角色权限关联关系在正确的租户上下文内，防止跨租户的权限越界。
    /// 2. 数据一致性：通过 TenantId 保证角色、权限、关联三者的租户归属一致，维护权限体系的完整性。
    /// 3. 独立配置：每个租户可独立配置自己的角色权限映射，实现完全定制化的权限管理体系。
    /// 4. 系统级映射：TenantId 为 null 表示系统级角色权限关联，通常用于系统管理员的通用权限配置。
    /// </remarks>
    public string? TenantId { get; set; }

    /// <summary>
    /// 操作类型
    /// </summary>
    /// <remarks>
    /// 1. 业务追踪：记录对角色权限关联的操作类型，支持权限变更的审计和追溯。
    /// 2. 状态管理：通过操作类型区分关联的当前状态（分配/撤销/更新），支撑业务逻辑判断。
    /// 3. 默认值：默认为 ASSIGN（分配），确保历史数据和新创建数据的兼容性。
    /// 4. 扩展支持：预留操作类型字段，便于未来扩展更多权限管理功能（如临时授权、过期回收等）。
    /// </remarks>
    public string OperationType { get; set; } = "ASSIGN";

    /// <summary>
    /// 角色导航属性（EF Core 关系配置）
    /// </summary>
    /// <remarks>
    /// 1. 权限追溯：通过此属性可访问关联角色的详细信息，支持"通过权限找角色"的业务场景。
    /// 2. 缓存优化：角色信息相对稳定，适合缓存提升查询性能，减少数据库访问压力。
    /// 3. 业务分析：支持权限使用情况分析（如哪些权限被广泛分配、哪些权限使用率低）。
    /// 4. 级联加载：在需要完整权限信息时，可通过 Include 显式加载关联的角色数据。
    /// </remarks>
    public virtual Role Role { get; set; } = null!;

    /// <summary>
    /// 权限导航属性（EF Core 关系配置）
    /// </summary>
    /// <remarks>
    /// 1. 权限详情访问：通过此属性可获取关联权限的完整信息（编码、名称、类型、资源路径等）。
    /// 2. 权限校验支撑：在权限验证时通过导航属性快速获取权限详情，支持精确的访问控制决策。
    /// 3. 界面渲染：为权限配置界面提供完整的权限信息，支持管理员直观地进行权限分配操作。
    /// 4. 性能平衡：采用延迟加载避免不必要的性能开销，在需要时按需加载权限详细信息。
    /// </remarks>
    public virtual Permission Permission { get; set; } = null!;
  }
}